Add SpEL support for nested username extraction in OAuth2 user info #16857

yybmion · 2025-04-01T12:02:14Z

This PR adds support for extracting usernames from nested properties in OAuth2 user info responses using SpEL expressions, addressing the limitation where providers wrap user data in nested objects.

Fixes #16390

Problem

OAuth2 providers (like X/Twitter) wrap user data in nested objects, requiring complex workarounds to extract usernames.

Solution

Commit 1: Allow injecting principal name into DefaultOAuth2User

Add username field to DefaultOAuth2User
Add static factory method withUsername() for direct username injection
Deprecate constructor that uses nameAttributeKey lookup
Maintain backward compatibility and serialization format

Commit 2: Add SpEL support for nested username extraction

Add usernameExpression property to ClientRegistration
Add username field to OAuth2UserAuthority
Support SpEL expressions for nested property access (e.g., "data.username")
Use SimpleEvaluationContext for secure expression evaluation
Update both DefaultOAuth2UserService and DefaultReactiveOAuth2UserService
Pass evaluated username directly to OAuth2UserAuthority for Expose user name attribute name in OAuth2UserAuthority #15012 compatibility

Backward Compatibility

No breaking changes - all existing APIs continue to work
Deprecated APIs remain functional with clear migration path

rwinch · 2025-05-07T16:41:45Z

Thanks for the PR @yybmion! I wonder if this might be better implemented using SpEL to provide more powerful options for resolving the username. What are your thoughts?

yybmion · 2025-05-07T17:51:24Z

Hi @rwinch , Thank you for your guidance on this.

I initially chose the dot notation approach because it offers a simple and intuitive solution specifically for the nested user-name-attribute issue.

However, I can see the value in using SpEL as you suggested. While I think it may be slightly more complex, SpEL provides much greater extensibility for future use cases beyond simple nested structures. The consistency with other parts of the Spring Security framework is also a advantage.

If you confirm that SpEL is the preferred direction, I'd be happy to update the PR accordingly.

rwinch · 2025-05-13T16:08:48Z

Yes. Please provide an implementation that uses SpEL.

yybmion · 2025-05-18T07:14:23Z

Hello @rwinch, I'd like to clarify your feedback on my PR about supporting nested properties in the user-name-attribute.

Did you mean that I should implement support for expressions like #{data.username} in the properties and yml configuration files to handle nested structures? (Instead using data.username)

Thank you for your guidance!

rwinch · 2025-05-21T15:09:53Z

I think an outline would be:

Allow Injecting the Principal Name into `DefaultOAuth2User`

Right now OAuth2UserService requires defining the name property as an attribute name. This limits the flexibility of resolving the name.

Update DefaultOAuth2User to allow injecting the name (rather than a property for obtaining the name). You would add a new member variable of username. This would likely require using a static factory method to distinguish from the existing constructor since the types of the nameAttributeKey and username are the same.

You can remove the nameAttributeKey member variable and instead populate the username using the attributes[nameAttributeKey] in the constructor if nameAttributeKey was specified.

Deprecate the old DefaultOAuth2User constructor in favor of injecting the name directly and update the usage of DefaultOAuth2User within Spring Security to no longer use the deprecated constructor.

Add SpEL Support

Update ClientRegistration to have a property named usernameExpression and remove the userNameAttributeName property but preserving and deprecating the methods which instead populate the usernameExpression member variable. This should be passive since the usernameAttributeName is a valid SpEL expression.

Update OAuth2UserService to extract the username using the usernameExpression property from the ClientRegistration as a SpEL expression with the attributes as the root object. Create the DefaultOAuth2User with the username injected into it rather than using the nameAttributeKey.

I think creating these as two separate commits is valuable since they are useful on their own. Let me know your thoughts.

yybmion · 2025-06-13T13:18:25Z

Hi @rwinch thank you for the detailed guide.

I've implemented the SpEL-based approach as outlined in the original issue. The solution provides

SpEL expressions for nested property access (e.g., "data.username")
Full backward compatibility with existing userNameAttributeName
Support for both sync and reactive implementations

Please see the PR description for detailed changes.

rwinch

Thank you for the updates. This is taking shape. I've provided feedback inline.

.../main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java

rwinch · 2025-06-23T18:52:02Z

...rc/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java

+					return this.usernameExpression;
+				}
+
+				return this.userNameAttributeName;


Please just return the usernameExpression without defaulting here. Instead ensure that the userNameAttributeName setter sets the usernameExpression.

rwinch · 2025-06-23T18:54:41Z

...rc/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java

@@ -672,7 +700,14 @@ private ProviderDetails createProviderDetails(ClientRegistration clientRegistrat
 			providerDetails.tokenUri = this.tokenUri;
 			providerDetails.userInfoEndpoint.uri = this.userInfoUri;
 			providerDetails.userInfoEndpoint.authenticationMethod = this.userInfoAuthenticationMethod;
+			if (this.usernameExpression != null) {


If you update the builder to set the expression when setting the userNameAttributeName, then the if statement can be removed

rwinch · 2025-06-23T20:55:15Z

.../main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java

-		return new DefaultOAuth2User(authorities, attributes, userNameAttributeName);
+
+		String evaluatedUsername = evaluateUsername(attributes, usernameExpression);
+		Collection<GrantedAuthority> authorities = getAuthorities(token, attributes, usernameExpression);


This is now passing in usernameExpression to getAuthorities which means that the usernameExpression is now passed into OAuth2UserAuthority in place of userNameAttributeName.

I think when users use more complex expressions it will break functionality introduced gh-15012 because the OAuth2UserAuthority only has an attribute name and not a property. We will need to figure out how to integrate cleanly with gh-15012 From the PR it sounds like we could just expose the username rather than the attribute, but I'm not certain how the integration is being used cc @filiphr

Thanks for highlighting this important integration issue with gh-15012!

I've addressed this by following your suggestion to expose the username directly rather than the attribute name.

Added username field to OAuth2UserAuthority with getUsername() method

Builder pattern: OAuth2UserAuthority.withUsername(evaluatedUsername)

Pass the evaluated username result (not the SpEL expression) to OAuth2UserAuthority

I think this way, OAuth2UserAuthority always receives the final evaluated username string, preserving compatibility with gh-15012 regardless of expression complexity.

...rc/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java

...uth2-core/src/main/java/org/springframework/security/oauth2/core/user/DefaultOAuth2User.java

- Add username field to DefaultOAuth2User for direct name injection - Add Builder pattern with DefaultOAuth2User.withUsername(String) static factory method - Deprecate constructor that uses nameAttributeKey lookup in favor of Builder pattern - Update Jackson mixins to support username field serialization/deserialization This change prepares for SpEL support in the next commit. Signed-off-by: yybmion <yunyubin54@gmail.com>

yybmion · 2025-06-25T14:38:50Z

Thanks for the feedback @rwinch ! I've addressed all the review comments and updated the code accordingly.

But the build failure appears to be related to Kotlin version. What would you recommend I do?

- Add usernameExpression property with SpEL evaluation support - Auto-convert userNameAttributeName to SpEL for backward compatibility - Use SimpleEvaluationContext for secure expression evaluation - Pass evaluated username to OAuth2UserAuthority for spring-projectsgh-15012 compatibility - Add Builder pattern to DefaultOAuth2User - Support nested property access (e.g., "data.username") Fixes spring-projectsgh-16390 Signed-off-by: yybmion <yunyubin54@gmail.com>

rwinch

This is getting very close!

Please address the comments and ensure to update the documentation (including the What's New Section)

rwinch · 2025-06-27T19:10:31Z

...h2-core/src/main/java/org/springframework/security/oauth2/core/user/OAuth2UserAuthority.java

@@ -44,6 +45,8 @@ public class OAuth2UserAuthority implements GrantedAuthority {

 	private final String userNameAttributeName;


This property should be deprecated as should all the methods/constructors that use it.

Please also address OidcUserAuthority which extends from this class. It will likely need it's own Builder that extends from this Builder and have an overridden withUsername static method.

rwinch · 2025-06-27T19:11:37Z

...h2-core/src/main/java/org/springframework/security/oauth2/core/user/OAuth2UserAuthority.java

+	 * the attributes - preserved for backwards compatibility
+	 * @param username the username
+	 */
+	private OAuth2UserAuthority(String authority, Map<String, Object> attributes, String userNameAttributeName,


since the Builder doesn't use usernameAttributeName, we shouldn't include this as a property here, so that this constructor does not deprecated properties.

rwinch · 2025-06-27T19:12:07Z

...h2-core/src/main/java/org/springframework/security/oauth2/core/user/OAuth2UserAuthority.java

+	 * the attributes - preserved for backwards compatibility
+	 * @param username the username
+	 */
+	private OAuth2UserAuthority(String authority, Map<String, Object> attributes, String userNameAttributeName,


Consider the order of username, authority, attributes since username is now a required property.

rwinch · 2025-06-27T19:12:39Z

...h2-core/src/main/java/org/springframework/security/oauth2/core/user/OAuth2UserAuthority.java

+	 * This method provides direct access to the username without requiring knowledge of
+	 * the attribute structure or SpEL expressions used to extract it.
+	 * @return the username
+	 * @since 6.5


The PR targets main, so this (and any other since) should be since 7.0

spring-projects-issues added the status: waiting-for-triage An issue we've not yet triaged label Apr 1, 2025

yybmion force-pushed the gh-16390 branch from 95efd3b to ef59929 Compare April 2, 2025 09:34

rwinch self-assigned this May 7, 2025

rwinch added in: oauth2 An issue in OAuth2 modules (oauth2-core, oauth2-client, oauth2-resource-server, oauth2-jose) type: enhancement A general enhancement and removed status: waiting-for-triage An issue we've not yet triaged labels May 7, 2025

rwinch added the status: waiting-for-feedback We need additional information before we can continue label May 7, 2025

spring-projects-issues added status: feedback-provided Feedback has been provided and removed status: waiting-for-feedback We need additional information before we can continue labels May 7, 2025

rwinch added status: waiting-for-feedback We need additional information before we can continue and removed status: feedback-provided Feedback has been provided labels May 13, 2025

spring-projects-issues added status: feedback-provided Feedback has been provided and removed status: waiting-for-feedback We need additional information before we can continue labels May 18, 2025

rwinch added status: waiting-for-feedback We need additional information before we can continue and removed status: feedback-provided Feedback has been provided labels May 21, 2025

This comment was marked as resolved.

Sign in to view

spring-projects-issues added status: feedback-provided Feedback has been provided and removed status: waiting-for-feedback We need additional information before we can continue labels May 25, 2025

yybmion force-pushed the gh-16390 branch 7 times, most recently from c5aa6d9 to 972afda Compare June 12, 2025 15:30

yybmion changed the title ~~Add support for nested user-name-attribute using dot notation~~ Add SpEL support for nested username extraction in OAuth2 user info Jun 12, 2025

rwinch requested changes Jun 23, 2025

View reviewed changes

rwinch added status: waiting-for-feedback We need additional information before we can continue and removed status: feedback-provided Feedback has been provided labels Jun 23, 2025

yybmion force-pushed the gh-16390 branch from 51255ff to 8854409 Compare June 25, 2025 05:17

yybmion force-pushed the gh-16390 branch 3 times, most recently from 0f6d3ce to 5798e87 Compare June 25, 2025 14:27

spring-projects-issues added status: feedback-provided Feedback has been provided and removed status: waiting-for-feedback We need additional information before we can continue labels Jun 25, 2025

yybmion force-pushed the gh-16390 branch from 5798e87 to adb119d Compare June 26, 2025 16:17

rwinch requested changes Jun 27, 2025

View reviewed changes

rwinch added status: waiting-for-feedback We need additional information before we can continue and removed status: feedback-provided Feedback has been provided labels Jun 27, 2025

		@@ -44,6 +45,8 @@ public class OAuth2UserAuthority implements GrantedAuthority {

		private final String userNameAttributeName;

Add SpEL support for nested username extraction in OAuth2 user info #16857

Are you sure you want to change the base?

Add SpEL support for nested username extraction in OAuth2 user info #16857

Uh oh!

Conversation

yybmion commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Commit 1: Allow injecting principal name into DefaultOAuth2User

Commit 2: Add SpEL support for nested username extraction

Backward Compatibility

Uh oh!

rwinch commented May 7, 2025

Uh oh!

yybmion commented May 7, 2025

Uh oh!

rwinch commented May 13, 2025

Uh oh!

yybmion commented May 18, 2025

Uh oh!

rwinch commented May 21, 2025

Allow Injecting the Principal Name into DefaultOAuth2User

Add SpEL Support

Uh oh!

This comment was marked as resolved.

yybmion commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rwinch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rwinch Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

rwinch Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

rwinch Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

yybmion Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yybmion commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rwinch left a comment

Choose a reason for hiding this comment

Uh oh!

rwinch Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

rwinch Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

rwinch Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

rwinch Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yybmion commented Apr 1, 2025 •

edited

Loading

Allow Injecting the Principal Name into `DefaultOAuth2User`

yybmion commented Jun 13, 2025 •

edited

Loading

yybmion Jun 25, 2025 •

edited

Loading

yybmion commented Jun 25, 2025 •

edited

Loading